
Keyboard Macros Help

                                          help version: 1.1
                                               created: 05/19/00 {11:44:50 am}
                                           last update: 03/06/01 {05:15:44 pm}


	  	What Is a Macro?


A macro is a sequence of recorded keystrokes that can be played back again. 
Unlike other macro packages you might be familiar with in other Mac
applications, keyboard macros in Alpha do not record mouse movement or
entries in system dialogs -- only keystrokes or menu selections are
recorded.  Even with these limitations, you will discover that macros can
save you time through easy automation of repetitive tasks.

Macros can also be used to attach any (previously unassigned) key binding
to any menu item.

When do you make a macro?  Whenever you find yourself typing the same
keystrokes over and over again, then a light should go off in your brain
telling you its time to make a macro.  Once you make a macro, you can name
it (that is, save it) for future use.  Over time you will build up a
library of macros that you can invoke any time you need them.

Things you can do with macros:

	*   basic textual markup
	*   reformat tables and files
	*   complex copying and pasting between edit windows

Alpha's implementation of macros is similar to that of Emacs, but there are
subtle differences.  Remember, Alpha is not Emacs!  You don't need to be an
Emacs guru to use keyboard macros in Alpha.  Since macros are a simple way
of creating valid Alpha text manipulation commands, every user will benefit
from a basic working knowledge of how to use macros.

See this "Macros Example" hyperlink for a little macros tutorial.


	  	Defining a Macro


Defining keyboard macros can be done with the "Utils --> Keyboard Macros"
menu.  This submenu has the following items:

	Menu Item               | Keystroke         | Action
	_________________________________________________________________________
	Start Keyboard Macro    | C-x (  or  F13    | Start recording keystrokes.
	End Keyboard Macro      | C-x )  or  F14    | End recording.
	Execute Keyboard Macro  | C-x e  or  F15    | Invoke last macro.


If you don't have an extended keyboard, you can change the F13, F14 and F15
key bindings using the "Config --> Packages --> Miscellaneous Packages"
menu item.

Begin recording a macro by selecting the "Start Keyboard Macro" menu item,
pressing its key-binding equivalent, or by typing "C-x (" -- the message
"Defining Keyboard Macro ..."  will appear in the status bar to inform you
that your subsequent keystrokes will be recorded.  Once you have started a
keyboard macro Alpha will record everything you type: commands and literal
text.  Remember, nothing you do with the mouse is recorded, so you should
move the point with cursor movement bindings.  (See "Emacs Help" for a list
of Emacs cursor movement bindings.)

To end the macro, use the "End Keyboard Macro" menu item, its key-binding,
or type "C-x )" -- this tells Alpha to stop recording your keystrokes.  A
recording session will terminate automatically if there is an error or if
you abort the macro by typing C-g (abortEm).

During macro recording, Alpha behaves normally responding to commands and
keystrokes; thus you will be able to see if your keystrokes are
appropriate.  If you make a mistake, unless it is a fatal one, you can
probably just type some extra corrective keystrokes and continue.  Macros
run so quickly that executing a few superfluous keystrokes will not
noticeably effect your macro's performance.  

Of course you can always abort the macro recording if you can remember the
keystrokes you need, or edit the macro after you save it using the menu
item "Macro Utils --> Edit Saved Macro".

To invoke your macro after you have recorded it, type C-x e (or use the
menu or key-binding ...).  Alpha will play back your keystrokes.  C-x e
invokes only the last recorded macro.  If you record a new macro without
naming the last macro, the last macro will be overwritten and lost.  Any
macro you want to save should be named.

The "Macros Example" hyperlink is still available for a tutorial !


	  	Saving Macros


The "Utils --> Macro Utils" menu allows you to save the last macro that you
created, and manipulate the collection of saved macros that are stored in
your preferences files.  The menu items include:


	Display Last Macro

Opens a new window displaying all of the commands saved in the last macro.


	Save Last Macro

Save the last created macro.  Prompts you to enter a name for your new
macro, and inserts this new name into the "Saved Macros" menu.  All saved
macros will be remembered upon subsequent restarts of Alpha.  Names should
be of the form "wordWord", as in "doubleSpace".  Any spaces in the name
that you enter will be removed, but Alpha will cleverly convert names with
capsWithinThem to a nice menu name.

Important: Do NOT try to save a macro with the name of a currently defined
procedure.  If you attempt to do so, you will be duly warned.  If you
ignore the warning, then you will remove the previously defined procedure
entirely, and you will have to both remove (or rename) the macro and
restart to retrieve the original.  So DON'T try to name a macro something
like "Save" or "Quit" !!!


	List Saved Macros

This item is dimmed if there are no currently saved macros.

Lists all of the saved macros.  Selecting any item in this list prints the
macro sequence as a list of Alpha commands in the current open window,
allowing the macro to be further refined and saved in a "prefs.tcl" file if
desired.


	Hide Saved Macros

This item is dimmed if there all saved macros are hidden.

Removes any saved macros from the "Saved Macros" menu, but does not delete
them permanently.  Any hidden macros can be shown again with ...


	Show Saved Macros

This item is dimmed if there are no currently hidden macros.

Re-inserts any previously hidden macros into the "Saved Macros" menu.


	Edit Saved Macro

This item is dimmed if there are no currently saved macros.

Opens a dialog allowing you to select any saved macro to be edited.  Once
you have made your selection, the macro's procedures will be displayed in a
new window.  After you have finished editing the macro (but with the window
still open), select this menu item again to save it in your preferences
folder.


	Delete Saved Macro

This item is dimmed if there are no currently saved macros.

Offers a list-pick dialog to delete any previously saved macros.  These
will be permanently removed from the "Saved Macros" menu.


	Rename Saved Macro

This item is dimmed if there are no currently saved macros.

Offers a list-pick dialog to select macros to be renamed, and then prompts
you for the new name of each macro selected.  The old names will then be
replaced (if currently not hidden) in the "Saved Macros" menu.



	====================================================================


The "Utils --> Saved Macros" menu contains all previously saved (and not
hidden) macros, and also allows you to assign key bindings to any saved
macro.  Macros that are hidden and subsequently re-shown will retain any
assigned key binding.

Note that key-bindings set by other menus or modes may take precedence over
the binding that you have selected.  Before choosing a binding, you should
use the "Config --> Describe Binding" menu item to ensure that the binding
that you want is avaiable.  See the "Default Key Bindings" file for more
information.


	  	Writing Good Macros


With practice you will become proficient at constructing macros which work
in all situations.  The most important principle in creating good macros is
the use of absolute, rather than relative commands.  In the double-space
example used in the "Macros Example", we used C-e to move to the end of the
line rather than spacing to the end of the line with a series of C-fs.  A
good macro will successfully work on the target text and prepare itself to
be repeated.  In this example, the last command in the macro moved the
cursor to the next line, precisely where it needs to be for the a repeat
performance.

While macros are an easy way to automate repetitive typing tasks, they are
not an alternative for writing your own procedures.  There are many things
that you can't do with a macro.  Loops, if-then conditionals, and searches
cannot be recorded with a macro (although they can be easily added.)  Some
macros might be good starting points, however, for scripting your own
procedures.


	  	Things That Don't Work


Emacs users will be used to setting up a macro with a search, C-s, command. 
Alpha is not Emacs!  Text typed into the status bar is not recorded.  The
command C-s (quickFind) is recorded, but none of the search text is.  In
order to couple your macro with a search you will have to learn a little
Tcl (as shown above).

Recursive edits do not work in Alpha.  All keystrokes you type during macro
recording are a collected.  (A recursive edit in Emacs is invoked with C-x
q or C-u C-x q and provides a way to pause the macro for user enterable
text.  While in the recursive edit, the keystrokes are not recorded. 
During the macro playback, the macro will pause for the user to enter text
when the recursive edit is encountered.)


	  	Differences Between Alpha and Emacs


In the double-space example used in the "Macros Example" tutorial, we used
C-e C-f to position the cursor on the next line.  C-n is just as good in
Alpha; unlike Emacs, Alpha does not add a new line to the buffer if C-n is
issued on the last line of the file.  If you use C-n in Alpha and call the
macro more times than there are lines in the file no extra lines are added.


	======================================================================


 Author: Donavan Hall
 E-mail: <hall@magnet.fsu.edu>

